home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 May / macformat-024.iso / Shareware City / Developers / forth-to-latex-pretty-print / F2L / Documentation / Manual.txt < prev    next >
Encoding:
Text File  |  1995-01-05  |  9.9 KB  |  258 lines  |  [TEXT/ALFA]
  1.  
  2.  
  3.                            Forth2LaTeX User's Manual
  4.  
  5.  
  6.                                      by   
  7.                                Ronald T. Kneusel
  8.                                  January 1995
  9.                                  
  10.                                    ver 1.9
  11.                                    
  12.  
  13.  
  14. Copyright
  15. ---------
  16.  
  17. This manual and the program it describes, along with all source files, is
  18. (c) 1994, by Ronald T. Kneusel.  All rights reserved.  Non-profit distribution 
  19. permitted as long as this manual is included and all copyright notices remain 
  20. intact.  Please inform me of any changes you make to at the email address below.
  21.  
  22. Ronald T. Kneusel
  23. 8725 West Burdick Avenue
  24. Milwaukee, WI 53227 USA
  25. (414) 545-7557
  26.  
  27. Internet: kneusel@studsys.mscs.mu.edu
  28.  
  29.  
  30. What is it?
  31. -----------
  32.  
  33. Forth2LaTeX is a program designed to format Forth source code for LaTeX.  It 
  34. presently runs in Modula-2 and C on the Macintosh and in C on Unix, VMS, and 
  35. MS-DOS.  This manual describes all versions noting differences where appropriate.
  36. Source code for both the C and Modula-2 versions is included for those 
  37. interested in modifying the program to suit their own needs.  Forth2LaTeX 
  38. intentionally knows little of Forth.  It knows what a \ comment is and the 
  39. words : (colon), VARIABLE, CONSTANT, CREATE, FVARIABLE, and FCONSTANT.  
  40. This does not tie it to a specific Forth system making Forth2LaTeX useful to 
  41. the widest possible audience.
  42.  
  43. Forth2LaTeX features include:
  44.  
  45.   *  Ability to bold word names when defined.
  46.   
  47.   *  Creating an index of defined words and the line on which the word was 
  48.      defined.
  49.   
  50.   *  Printing useful program information.
  51.   
  52.   *  Complete LaTeX  access from within the source code in three different ways.
  53.   
  54.   *  Different type styles for code and comments.
  55.   
  56.   *  Ability to create a table of contents and section the code in a way 
  57.      similar to LaTeX.
  58.   
  59.   *  Command files allow processing groups of files at a single time.
  60.  
  61. Forth2LaTeX does impose one minor constraint on the programmer, namely, it 
  62. only recognizes \ comments and therefore will treat comments in
  63. parentheses as code.  This is really a minor inconvenience as parentheses 
  64. are usually reserved for stack effects comments.
  65.  
  66.  
  67. Getting Started - A Guide for the Impatient
  68. -------------------------------------------
  69.  
  70. If your copious free time is insufficient to allow a complete reading of 
  71. this little manual, this is a good place to start.  The guide is divided 
  72. by computer: Macintosh or Everyone Else.
  73.  
  74. ** Macintosh **
  75.  
  76. Double-click the Forth2LaTeX application to get it going.  All parameters can 
  77. be set via the SETTINGS menu.  Just choose the setting and it toggles 
  78. between on or off.  Switching between REPORT and ARTICLE for the style 
  79. will use the respective LaTeX document style.  Typically, longer programs 
  80. make sense as reports while shorter programs are articles.  Chapter 
  81. sectioning may only be used (or rather is ignored unless) the style is set 
  82. to REPORT.  Leave the COMMENTS as FORTH unless you have included LaTeX code 
  83. in the comments and did not use the ` (backquote) escape character.
  84.  
  85. Choose OPEN... from the FILE menu and select a Forth source code file.  If 
  86. the filename ends in .4th, .fth, or .forth the extension will be stripped.  
  87. Select an output filename using either the one suggested or your own with 
  88. .tex appended.  Forth2LaTeX will process the file and report how many lines 
  89. were processed when finished.
  90.  
  91. ** Everyone Else **
  92.  
  93. Enter 'Forth2LaTeX' on the command line to see a quick help screen listing 
  94. the format and switches.  Most a self-explanatory in nature, the rest are 
  95. described below.
  96.  
  97.  
  98. Controlling Forth2LaTeX
  99. -----------------------
  100.  
  101. There are two ways of controlling the operation of Forth2LaTeX: via menu or 
  102. command line switches, or via Forth comments within the source code.  
  103. The latter will always override the former.  Needless to say, only the 
  104. Macintosh version uses menus, the rest use command line switches.
  105.  
  106. ** Source Code **
  107.  
  108. All versions of Forth2LaTeX can be controlled by comment statements within the 
  109. Forth source code.  It is important to note that spacing and capitalization 
  110. _are_ important.
  111.  
  112. *** Settings ***
  113.  
  114. Forth2LaTeX settings and information about the program are entered in the 
  115. following form:
  116.  
  117.    \ Program: <program name>   -- name of the program
  118.    \ Author: <author name>     -- name of the author, appears in the title
  119.    \ Started: <date>           -- date program begun
  120.    \ Modified: <date>          -- date of last modification
  121.    \ Modify By: <name>         -- person doing the modification
  122.    \ Summary: <single line>    -- a one line summary of the program
  123.    
  124.    \ Comments: FORTH           -- comments are as normal
  125.    \ Comments: LATEX           -- comments are treated as LaTeX code
  126.    
  127.    \ Uppercase: ON or OFF      -- force all but strings and comments to
  128.                                   uppercase
  129.                                   
  130.    \ Table of Contents: ON | OFF  -- make a table of contents, use with
  131.                                      sectioning
  132.    
  133.    \ Index: ON | OFF           -- output an alphabetical index of defined words
  134.    
  135.    \ Bold: ON | OFF            -- bold colon definitions
  136.    
  137.    \ Style: REPORT             -- use \documentstyle{report}
  138.    \ Style: ARTICLE            -- use \documentstyle{article}
  139.  
  140.  
  141. Certain characters have a special meaning to LaTeX and need to be escaped
  142. by prefixing with a \ when use normally. Forth2LaTeX does this automatically 
  143. for code, including the spaces to force LaTeX to preserve the indentations, 
  144. but can be told to stop this for comments.  The default setting is FORTH 
  145. which escapes the text in comments as elsewhere.  Changing COMMENTS to LATEX 
  146. allows the programmer to include LaTeX code in the comments, but also makes 
  147. the programmer responsible for using appropriate escape sequences when 
  148. necessary.  Note that the settings above can appear anywhere within the source 
  149. code, but must appear in the first file to be processed when using multiple 
  150. files.
  151.  
  152. *** Sectioning ***
  153.  
  154. Forth2LaTeX recognizes the standard LaTeX sectioning commands, though it 
  155. ignores chapters unless in REPORT style.  Sectioning provides a convenient 
  156. way to organize the source code and to create a table of contents that 
  157. outlines the program structure.  To use sectioning, include statements 
  158. giving the name of the section prefixed by the type of section:
  159.  
  160.    \ Chapter: <chapter-name>   -- start a chapter (LaTeX \chapter)
  161.    
  162.    \ Section:                  -- sections and subsections
  163.    \ Subsection:
  164.    \ Subsubsection:
  165.  
  166.  
  167. *** Other Ways of Including LaTeX Code ***
  168.  
  169. The Comments: setting described above is only one of three ways to include 
  170. LaTeX code in the Forth source code.  The others are to use a special LaTeX 
  171. escape character or to use a \ . to prefix a line that will be passed as is 
  172. into the output file.  The former is most useful for inserting a small piece 
  173. of code:
  174.  
  175. \  `$c_{m}$` is set here
  176.  
  177. appears as: $\backslash$\ \  $c_{m}$ is set here
  178.  
  179. The escape character is ` (backquote).  Everything between backquotes is 
  180. immune to special character escaping and can include valid LaTeX statements.
  181.  
  182. To include an entire line, useful for entering normal text, prefix the 
  183. line with a \ . where every character after the period is sent as is into 
  184. the output file without escaping or forcing into a single line:
  185.  
  186. \ .This will appear in the output as if it were entered into a normal
  187. \ .LaTeX document.  This could be used to insert large blocks of text
  188. \ .describing the code, or to even include graphics.
  189.  
  190.  
  191. ** Command Line Switches and Menu Settings **
  192.  
  193. It is possible change Forth2LaTeX settings without specifically stating the 
  194. settings in the source code.  The Macintosh uses a menu called (surprisingly) 
  195. SETTINGS to adjust Forth2LaTeX values prior to processing a file.  Each of the 
  196. menu items has a direct counter part in the source code settings given above.
  197.  
  198. Other computers use command line switches to alter the functioning of 
  199. Forth2LaTeX.  The general format is: 
  200.  
  201.   Forth2LaTeX <source-file>  <switches>
  202.  
  203. where the <switches> consists of a string of characters (case is irrelevant) 
  204. prefixed with a - (dash).  No switches need be specified.  The options are 
  205. listed below:
  206.  
  207.     u  -- uppercase code (does not alter comments)
  208.     l  -- comments LATEX (default is FORTH)
  209.     t  -- generate table of contents
  210.     i  -- index of defined words
  211.     b  -- bold colon definition names
  212.     r  -- style is REPORT (default is ARTICLE)
  213.  
  214.  
  215. ** Multiple Files **
  216.  
  217. If Forth2LaTeX is presented a file with a .f2l extension it will assume it to 
  218. be a command file that contains the names of a series of files to be processed.
  219. Comments, preceeded by a # character, may be added to the file.  
  220. A sample command file could be:
  221.  
  222. # The following specifies the output file name, default is 'a.tex'
  223.  
  224. # Output: Alexis.tex
  225.  
  226. # These are the files to be processed, in order:
  227.  
  228.      Setup.4th         # mainly memory management, constants, etc.
  229.      Arith.4th         # big integer and rational arithmetic and utilities
  230.      Poly.4th          # univariate polynomial routines and utilities
  231.      Command.4th       # Yerk code and command processor
  232.      Intrinsic.4th     # Built-in commands
  233.  
  234. # That's all folks!
  235.  
  236.  
  237. The third line above is used to specify the output file name, which 
  238. defaults to a.tex.  Unless complete path names are given in the 
  239. command file Forth2LaTeX assumes that the files can be found in the current 
  240. directory.  Use a command file when working on a larger project with 
  241. multiple files.
  242.  
  243.  
  244. Conclusion
  245. ----------
  246.  
  247. It is sincerely hoped that Forth2LaTeX will be of use to you.  It is also hoped
  248. that users will feel free to alter the source code for any of the versions, 
  249. provided that the author is sent a copy if the modified version is to be 
  250. released publicly.
  251.  
  252. Suggestions and bug reports (Bugs? What are those?) are to be sent to the 
  253. email address given at the beginning of this document.  The author assumes no 
  254. responsibility of any kind for any loss of data or time that may be 
  255. caused by the use of this program.  While it is unlikely that something 
  256. will happen, if it does, I'm not to blame.
  257.  
  258.